sa-learn - train SpamAssassin's Bayesian classifier
sa-learn [options] --file message
sa-learn [options] --mbox mailbox
sa-learn [options] --dir directory
sa-learn [options] --single < message
Options:
--ham Learn messages as ham (non-spam) --spam Learn messages as spam --forget Forget a message --rebuild Rebuild the database if needed --force-expire Force an expiry run, rebuild every time -f file, --folders=file Read list of files/directories from file --dir Learn a directory of RFC 822 files --file Learn a file in RFC 822 format --mbox Learn a file in mbox format --showdots Show progress using dots --no-rebuild Skip building databases after scan -L, --local Operate locally, no network accesses -C file, --config-file=file Path to standard configuration dir -p prefs, --prefs-file=file Set user preferences file -D, --debug-level Print debugging messages -V, --version Print version -h, --help Print usage message
Given a typical selection of your incoming mail classified as spam or ham (non-spam), this tool will feed each mail to SpamAssassin, allowing it to 'learn' what signs are likely to mean spam, and which are likely to mean ham.
Simply run this command once for each of your mail folders, and it will ''learn'' from the mail therein.
Note that globbing in the mail folder names is supported; in other words,
listing a folder name as * will scan every folder that matches.
SpamAssassin remembers which mail messages it's learnt already, and will not re-learn those messages again, unless you use the --forget option.
If you make a mistake and scan a mail as ham when it is spam, or vice versa, simply rerun this command with the correct classification, and the mistake will be corrected. SpamAssassin will automatically 'forget' the previous indications.
(Thanks to Michael Bell for this section!)
For a more lengthy description of how this works, go to http://www.paulgraham.com and see ``A Plan for Spam''. It's reasonably readable, even if statistics make me break out in hives.
The short semi-inaccurate version: Given training, a spam heuristics engine can take the most ``spammy'' and ``hammy'' words and apply probablistic analysis. Furthermore, once given a basis for the analysis, the engine can continue to learn iteratively by applying both it's non-Bayesian and Bayesian ruleset together to create evolving ``intelligence''.
SpamAssassin 2.50 supports Bayesian spam analysis, in the form of the BAYES rules. This is a new feature, quite powerful, and is disabled until enough messages have been learnt.
The pros of Bayesian spam analysis:
And the cons:
With Bayesian analysis, it's all probabilities - ``because the past says it's likely as this falls into a probablistic distribution common to past spam in your systems''. Tell that to your users! Tell that to the client when he asks ``what can I do to change this''. (By the way, the answer in this case is ``use whitelisting''.)
Still interested? Ok, here's the guidelines for getting this working.
First a high-level overview:
sa-learn --spam /path/to/spam/folder
sa-learn --ham /path/to/ham/folder
...
Let SpamAssassin proceed, learning stuff. When it finds ham and spam it will add the ``interesting tokens'' to the database.
cat mailmessage | sa-learn --ham --no-rebuild --single
This is handy for binding to a key in your mail user agent. It's very fast, as
all the time-consuming stuff is deferred until you run with the --rebuild
option.
Learning filters require training to be effective. If you don't train them, they won't work. In addition, you need to train them with new messages regularly to keep them up-to-date, or their data will become stale and impact accuracy.
You need to train with both spam and ham mails. One type of mail alone will not have any effect.
Note that if your mail folders contain things like forwarded spam, discussions of spam-catching rules, etc., this will cause trouble. You should avoid scanning those messages if possible. (An easy way to do this is to move them aside, into a folder which is not scanned.)
Another thing to be aware of, is that typically you should aim to train with at least 1000 messages of spam, and 1000 ham messages, if possible. More is better, but anything over about 5000 messages does not improve accuracy significantly in our tests.
Be careful that you train from the same source -- for example, if you train on old spam, but new ham mail, then the classifier will think that a mail with an old date stamp is likely to be spam.
It's also worth noting that training with a very small quantity of ham, will produce atrocious results. You should aim to train with at least the same amount (or more if possible!) of ham data than spam.
On an on-going basis, it's best to keep training the filter to make sure it has fresh data to work from. There are various ways to do this:
(An easy way to do this, by the way, is to create a new folder for 'deleted' messages, and instead of deleting them from other folders, simply move them in there instead. Then keep all spam in a separate folder and never delete it. As long as you remember to move misclassified mails into the correct folder set, it's easy enough to keep up to date.)
SpamAssassin does not support this method, due to experimental results which strongly indicate that it does not work well, and since Bayes is only one part of the resulting score presented to the user (while Bayes may have made the wrong decision about a mail, it may have been overridden by another system).
It should be supplemented with some supervised training in addition, if possible.
This is the default, but can be turned off by setting the SpamAssassin
configuration parameter auto_learn to 0.
message(s) as ham. If you have previously learnt
any of the messages as spam, SpamAssassin will forget them first, then
re-learn them as ham. Alternatively, if you have previously learnt
them as ham, it'll skip them this time around.
message(s) as spam. If you have previously learnt
any of the messages as ham, SpamAssassin will forget them first, then
re-learn them as spam. Alternatively, if you have previously learnt
them as spam, it'll skip them this time around.
sa-learn --rebuild once all the folders have been
scanned.
Note that this is currently ignored, as current versions of SpamAssassin will not perform network access while learning; but future versions may.
sa-learn and the other parts of SpamAssassin's Bayesian learner, use a set of persistent database files to store the learnt tokens, as follows.
This database also contains some 'magic' tokens, as follows: the number of ham and spam messages learnt, the number of tokens in the database, the message-count of the last expiry run, the message-count of the oldest token in the database, and the message-count of the current message (to the nearest 5000).
This is a database file, using the first one of the following database modules
that SpamAssassin can find in your perl installation: DB_File, GDBM_File,
NDBM_File, or SDBM_File.
This is a database file, using the first one of the following database modules
that SpamAssassin can find in your perl installation: DB_File, GDBM_File,
NDBM_File, or SDBM_File.
When you run sa-learn --rebuild, the journal is read, and the tokens that
were accessed during the journal's lifetime will have their last-access time
updated in the bayes_toks database.
sa-learn command is run, the 'message count' is increased by one.
This is used to control expiration of old tokens.
Since many processes may be running simultaneously, SpamAssassin does not
use a locked database file for this operation; instead, it uses the size
of this file as a counter, appending one byte for each message. Once it
hits 5000 bytes, the bayes_toks database is locked, and the message
counter entry in that database is increased accordingly.
Since SpamAssassin auto-learns, the Bayes database files could increase perpetually until they fill your disk or you run out of memory. To control this, SpamAssassin performs expiration.
Every bayes_expiry_scan_count / 2 messages, or when sa-learn --rebuild
--force-expire is run, SpamAssassin will attempt an expiry run, as follows.
SpamAssassin runs through every token in the database. If that token has not
been used during the scanning of the last bayes_expiry_scan_count messages,
it is marked for deletion.
Next, if that operation would bring the number of tokens below the
bayes_expiry_min_db_size threshold, it removes tokens from the for-deletion
list until the resulting database would contain bayes_expiry_min_db_size
token entries.
It then removes the listed tokens and updates the 'last expiry' setting.
The SpamAssassin configuration settings which control this operation are:
bayes_expiry_min_db_size is part of the SpamAssassin configuration.
The default value is 100000, which is roughly equivalent to a 5Mb database file
if you're using DB_File.bayes_expiry_scan_count is also part of the SpamAssassin
configuration. The default value is 5000.
The sa-learn command is part of the Mail::SpamAssassin Perl module.
Install this as a normal Perl module, using perl -MCPAN -e shell,
or by hand.
No environment variables, aside from those used by perl, are required to be set.
Mail::SpamAssassin(3)
spamassassin(1)
http://www.paulgraham.com/ , Paul Graham's ``A Plan For Spam'' paper
http://radio.weblogs.com/0101454/stories/2002/09/16/spamDetection.html , Gary
Robinson's f(x) and combining algorithms, as used in SpamAssassin
http://www.bgl.nu/~glouis/bogofilter/test6000.html , discussion of various Bayes training regimes, including 'train on error' and unsupervised training
Justin Mason <jm /at/ jmason.org>